<!DOCTYPE html>
<html lang="en">

<head>
	<meta charset="UTF-8"/>
	<meta name="keywords" content="Script Menu, script, script bundle, hook"/>
	<link rel="stylesheet" href="../../Shared/sty/standard.css"/>
	<script defer src="../../Shared/js/toc.js"></script>
	
	<title>Run script on specific events in CotEditor on Mac</title>
</head>

<body>

<h1>Run script on specific events in CotEditor on Mac scripts</h1>

<p>With scripting hooks, you can execute CotEditor scripts on certain events.</p>

<p>The following events are available with CotEditor:</p>
<ul>
	<li><p><code>document opened</code> : after you opened the file and then the content was loaded</p></li>
	<li><p><code>document saved</code> : after you saved the file and then the content was stored</p></li>
</ul>

<p>See “CotEditor Event Handler suite” section on AppleScript Dictionary for further information.</p>

<section>
<h2>Support scrpt the hooking</h2>

<p>Scripts with scripting hook must conform to the following protocols:</p>

<ul>
	<li><p>Written in AppleScript or JavaScript for Automation (JXA)</p></li>
	<li><p>Stored in the form of a script bundle (.scptd)</p></li>
</ul>

<p>In addition, events to subscribe to and handlers for them must be declared, as described below.</p>
</section>


<section>
<h2>Declare hooking in the script bundle</h2>

<p>A script bundle is a package-type file format that has the following folder structure:</p>

<pre>
HookingScript.scptd
└── Contents
    ├── Info.plist
    └── Resources
        ├── Script Libraries
        │   └── my-fancy-library.scpt
        ├── Scripts
        │   └── main.scpt
        └── description.rtfd
            └── TXT.rtf
</pre>

<p>Any scripts can be exported in this form with Script Editor, which is one of the standard applications distributed with macOS.</p>

<p>To support scripting hooks, the list of events to subscribing must be written in Contents/Info.plist. Info.plist is a property list containing the metadata of the bundle and formatted in XML like the following example:</p>

<pre class="source">
<code><span class="type">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="type">&lt;!DOCTYPE plist PUBLIC &quot;-//Apple//DTD PLIST 1.0//EN&quot; &quot;http://www.apple.com/DTDs/PropertyList-1.0.dtd&quot;&gt;</span>
<span class="tag">&lt;plist</span> <span class="attribute">version=</span><span class="string">&quot;1.0&quot;</span><span class="tag">&gt;</span>
  <span class="tag">&lt;dict&gt;</span>
    <span class="tag">&lt;key&gt;</span>CFBundleIdentifier<span class="tag">&lt;/key&gt;</span>
    <span class="tag">&lt;string&gt;</span>com.coteditor.hooking-script<span class="tag">&lt;/string&gt;</span>
    <span class="tag">&lt;key&gt;</span>CFBundleName<span class="tag">&lt;/key&gt;</span>
    <span class="tag">&lt;string&gt;</span>Hooking Script<span class="tag">&lt;/string&gt;</span>
    <span class="tag">&lt;key&gt;</span>CFBundleShortVersionString<span class="tag">&lt;/key&gt;</span>
    <span class="tag">&lt;string&gt;</span>1.0<span class="tag">&lt;/string&gt;</span>
  <span class="tag">&lt;/dict&gt;</span>
<span class="tag">&lt;/plist&gt;</span>
</code></pre>

<p>The events to subscribe must be stored at the key <code>CotEditorHandlers</code> and in the form of <code>array</code> of <code>string</code>. For example, to run a script automatically when opening and saving a document, write as follows:</p>

<pre class="source">
<code><span class="tag">&lt;key&gt;</span>CotEditorHandlers<span class="tag">&lt;/key&gt;</span>
<span class="tag">&lt;array&gt;</span>
  <span class="tag">&lt;string&gt;</span>document opened<span class="tag">&lt;/string&gt;</span>
  <span class="tag">&lt;string&gt;</span>document saved<span class="tag">&lt;/string&gt;</span>
<span class="tag">&lt;/array&gt;</span>
</code></pre>
</section>


<section>
<h2>Describe event handling</h2>

<p>An event handler is a block to receive certain events that the application caused and do something with the received event. In this section, the manners to write an event handler are described with a simple example, which shows the dialog on opening and saving a file.</p>

<h3>AppleScript</h3>

<p>In AppleScript, handlers are written with a <code>using terms from</code> block and <code>on</code> blocks.</p>

<pre class="source">
<code><span class="keyword">using terms from</span> <span class="type">application</span> <span class="string">&quot;CotEditor&quot;</span>
    <span class="keyword">on</span> <span class="command">document opened</span> <span class="variable">theDocument</span>
        <span class="command">write to console</span> <span class="string">&quot;Opened &quot;</span> &amp; (<span class="variable">theDocument's</span> <span class="attribute">name</span>)
    <span class="keyword">end</span> <span class="command">document opened</span>

    <span class="keyword">on</span> <span class="command">document saved</span> <span class="variable">theDocument</span>
        <span class="command">write to console</span> <span class="string">&quot;Saved &quot;</span> &amp; (<span class="variable">theDocument's</span> <span class="attribute">name</span>)
    <span class="keyword">end</span> <span class="command">document saved</span>
<span class="keyword">end</span> <span class="keyword">using terms from</span>
</code></pre>

<h3>JavaScript for Automation (JXA)</h3>

<p>In JavaScript for Automation, <code>function</code> statements on the global object creates handlers.</p>

<pre class="source">
<code><span class="variable">CotEditor</span> = <span class="variable">Application</span><span class="p">.</span><span class="command">currentApplication</span><span class="p">()</span>
<span class="variable">CotEditor</span><span class="p">.</span><span class="attribute">includeStandardAdditions</span> = <span class="value">true</span>

<span class="keyword">function</span> <span class="command">documentOpened</span><span class="p">(</span><span class="variable">document</span><span class="p">)</span> <span class="p">{</span>
  <span class="variable">CotEditor</span><span class="p">.</span><span class="command">writeToConsole</span><span class="p">(</span><span class="string">&quot;Opened &quot;</span> + <span class="variable">document</span><span class="p">.</span><span class="command">name</span><span class="p">())</span>
<span class="p">}</span>

<span class="keyword">function</span> <span class="command">documentSaved</span><span class="p">(</span><span class="variable">document</span><span class="p">)</span> <span class="p">{</span>
  <span class="variable">CotEditor</span><span class="p">.</span><span class="command">writeToConsole</span><span class="p">(</span><span class="string">&quot;Saved &quot;</span> + <span class="variable">document</span><span class="p">.</span><span class="command">name</span><span class="p">())</span>
<span class="p">}</span>
</code></pre>
</section>


<section id="cf">
<h2>See also</h2>
<ul>
	<li><a href="script_overview.html">Automate tasks with scripting in CotEditor on Mac</a></li>
	<li><a href="script_menu.html">Customize the Script menu in CotEditor on Mac</a></li>
	<li><a href="script_osascript.html">Automate tasks using AppleScript in CotEditor on Mac</a></li>
</ul>
</section>

</body>
</html>
